Xi-Language Reference: 2D Plots

    • axis (Manipulation of axes)
    • contour (Draws a contour plot)
    • endbuffer (Close a command buffer)
    • flushbuffer (Flush a command buffer)
    • getPlot (Query parameters of a plot)
    • line (Draws a line or (unfilled) polygon)
    • loadct (Changes the Colortable of a device)
    • plot (General plotting function)
    • point (Sets one or more points or markers)
    • rect (Draws filled and unfilled rectangles)
    • show (Draws a image)
    • startbuffer (Open a command buffer)
    • velocity_field (draws a velocity_field)
    • window (Opens a window and changes it's properties)
    • xyouts (Draws text at arbitrary places)

    axis (Manipulation of axes)

    Parameters

              axis ( num = 0, range = {}, title = "", titleheight = 0.05, 
                     numheight = 0.05, sticklen = 0.01, lticklen = 0.02, 
                     inside = 0, outside = 0, nonum = 0, noticks = 0, 
                     left = 0, right = 0, top = 0, bottom = 0, all = 0, 
                     remove = 0 )
    
              Types: num                    int
                     range                  double[]
                     title                  string
                     titleheight            double
                     numheight              double
                     sticklen               double
                     lticklen               double
                     inside                 int
                     outside                int
                     nonum                  int
                     noticks                int
                     left                   int
                     right                  int
                     top                    int
                     bottom                 int
                     all                    int
                     remove                 int
    

    Return

              -1
    

    Description

    The axis function is useful whenever you want to change the axes of a plot in a manner the plot function didn't offer or if you want to attach more than one axis to a plot.

    Use the left, right, top and/or bottom flags to define, which side of the actual plot you want to manipulate. The all flag is merely a synonym for all four flags i.e. all sides of a plot will be changed.

    With the num argument you are able to add and change more than one axis at the side of the actual plot (counted from inside to outside). Use the remove flag to remove a axis.

    With title you may change the title of the specified axis. The titleheight and numheight arguments changes the textheights of the title respectively of the numbers. The sticklen and lticklen arguments changes the lengths of the short respectively long ticks. Use the inside flag if you prefer the ticks to the inside of the plot and outside if they should point outwards. The nonum and noticks flags are shortcuts for numheight=0.0 and sticklen=lticklen=0.0 i.e. no number respectively on ticks will be drawn at all. Use nonum combined with noticks if the axis is merely a line (useful, if you have used the noaxis flag of the plot function).

    See also

    plot

    contour (Draws a contour plot)

    Parameters

              contour ( z, x = {}, y = {}, levels = {}, nlevels, 
                        labels = {}, nlables, curve = 0, color = -1 )
    
              Types: z                      double[]
                     x                      double[]
                     y                      double[]
                     levels                 double[]
                     nlevels                int
                     labels                 string[]
                     nlables                int
                     curve                  int
                     color                  int
    

    Return

              -1
    

    Description

    contour draws a contour plot of a 2-dimensional function z. If x and y are not given contour takes the indices of z as x and y coordinates. Otherwise you can specify the x and y coordinates of each point. x and y must have the same dimensions as z.

    The nlevels argument explicitly sets the number of levels contour should use. Tell contour at which z-values you want a contour line to be drawn with the levels argument.

    With lables and nlables you optionally put put some lables on the contour lines. If you set nlables exacly this number of lables containing the z-Values will be plotted. If you set lables you may plot arbitrary lables.

    With color you define which color the contour lines should have. And with the curve flag you choose whether the contour lines are mere polygons or cubit splines.


    endbuffer (Close a command buffer)

    Parameters

              endbuffer ( )
    

    Return

              -1
    

    Description

    See startbuffer for detail.

    See also

    startbuffer, flushbuffer

    flushbuffer (Flush a command buffer)

    Parameters

              flushbuffer ( )
    

    Return

              -1
    

    Description

    See startbuffer for detail.

    See also

    startbuffer, endbuffer

    getPlot (Query parameters of a plot)

    Parameters

              getPlot ( table )
    
              Types: table                  char[]
    

    Return

              double[]  (Containing the parameters)
    

    Description

    The getPlot is especially useful in connection with the X device. If you resize and reposition the plots with the mouse, you can use this function to query the new parameters.

    With the num parameter you select the plot you want to query. Use the xrange,yrange or position flag if you want the actual xrange, yrange respectively position of the specified plot.

    Example

     (  1)>plot(x=interval(-10,10),sin(x),\line);
     Function interval defined
     (  2)>print(getPlot(\xrange))
     <dblarr>
              -10           10 
     (  3)>print(getPlot(\yrange))
     <dblarr>
     -0.999573603  0.999573603 
     (  4)>print(getPlot(\position))
     <dblarr>
                0            0            1            1 
    

    See also

    plot

    line (Draws a line or (unfilled) polygon)

    Parameters

              line ( x1 = {}, y1 = {}, x1, y2, color = -1 )
    
              Types: x1                     double/double[]
                     y1                     double/double[]
                     x1                     double
                     y2                     double
                     color                  int
    

    Return

              -1
    

    Description

    line is an interface for the plot function. If x1 and y1 are simply numbers the parameters x2 and y2 must also be specified. In this case line draws a straight line form x1,y1 to x2,y2 with the color color. If x1 and y1 are arrays, x2 and y2 should be left blank. In this case line acts the same way as the plot function with the line flag set.

    See also

    plot

    loadct (Changes the Colortable of a device)

    Parameters

              loadct ( table )
    
              Types: table                  char[]
    

    Return

              -1
    

    Description

    The loadct function sets the colortable of the actual device. This is especially useful when displaying images. Note that the two first colors (0 (background) and 1 (foreground)) could not be changed by this function. Also remember, that loadct is pretty useless if you use the show function with fitColors enabled.

    See also

    show

    plot (General plotting function)

    Parameters

              plot ( x = {}, y = {}, xerr = {}, yerr = {}, color = -1, 
                     xrange = {}, yrange = {}, title = "", xtitle = "", 
                     ytitle = "", titleheight = 0.05, xtitleheight = 0.05, 
                     ytitleheight = 0.05, numheight = 0.05, num = 0, 
                     position = {}, erase = 0, line = 0, curve = 0, 
                     marker = 0, rect = 0, fillrect, noaxis = 0, 
                     hist = 0, histzero = 0.0, linestyle = {}, xlog = 0, 
                     ylog = 0 )
    
              Types: x                      double[]
                     y                      double[]
                     xerr                   double[]
                     yerr                   double[]
                     color                  int
                     xrange                 double[]
                     yrange                 double[]
                     title                  string
                     xtitle                 string
                     ytitle                 string
                     titleheight            double
                     xtitleheight           double
                     ytitleheight           double
                     numheight              double
                     num                    int
                     position               double[]
                     erase                  int
                     line                   int
                     curve                  int
                     marker                 int
                     rect                   int
                     fillrect               int
                     noaxis                 int
                     hist                   int
                     histzero               double
                     linestyle              int[]
                     xlog                   int
                     ylog                   int
    

    Return

              -1
    

    Description

    plot is a general graphical output function that should work for the most purposes. x and y are generally arrays filled with x and y coordinates. They should be of the same dimension. If not so one of them will be truncated to match the dimension of the other. If nothing more is determined plot simply sets points at the given coordinates. The x- and y-ranges will be set suitably.

    xerr and yerr are arrays that should be of the same dimension as x and y. xerr and yerr define the absolute errors (positiv number) of the given points. If one or both are given plot draws errorbars around each datapoint.

    xrange and yrange set the x and y ranges of the plot, both can be changed afterwards. title sets the title of the whole plot, xtitle and ytitle set the titles of the x- and y-axis. With titlehight, xtitleheight, ytitleheight and numheight you may define the textheight of the several titles and numbers at the axes.

    If the line flag is set the points will be connected by straight lines. The curve flag indicates that the points should be connected by a spline curve. Note that in this case spline means a spline in the plane not a function of the x coordinates (use the spline function for something like this). The rect and fillrect options are useful to draw filled and unfilled rectangles, each rectangle is defined by two points.

    With the use of marker a special marker around each point can be drawn. Actually the following markers are known:

        1           a "x" sign
        2           a "+" sign
        3           a "*" sign (more exactly a "x" together with "+")
        4           a small triangle
        5           a small diamond
        6           a small square
     
    If marker is set to any other value simply a point is drawn.

    color sets the drawing color. The displayed color depends on the number of bits per pixel the graphic-device supports.

    The num and position are useful if you want to draw more than one plot in a graphic-device. num simply sets the number of the actual plot or opens a new one. With position you define device-normal-coordinates where the plot num should be located.

    noaxis instructs Xi to draw no axis.

    If the parameter hist is set a histogram will ploted. The parameter histzero determine the minimum of the histogram (default is zero).

    Finally with xlog and ylog you enable the logarithmic scaling of the x- respectivly y-axis. Note, that in the case all x- respectivly y-coordinates have to be greater than zero.


    point (Sets one or more points or markers)

    Parameters

              point ( x = {}, y = {}, color = -1, marker = 0 )
    
              Types: x                      double/double[]
                     y                      double/double[]
                     color                  int
                     marker                 int
    

    Return

              -1
    

    Description

    The point function is an easy interface for the plot function. If x and y are merely numbers points sets a single point or marker (set by the marker parameter) with the color color. If x and y are arrays point sets a bunch of points or markers at once.

    See also

    plot

    rect (Draws filled and unfilled rectangles)

    Parameters

              rect ( x1 = {}, y1 = {}, x1, y2, color = -1, fill = 0 )
    
              Types: x1                     double/double[]
                     y1                     double/double[]
                     x1                     double
                     y2                     double
                     color                  int
                     fill                   int
    

    Return

              -1
    

    Description

    rect is an interface for the plot function. The fill flag defined whether the drawn rectangles should be filled or not. If x1 and y1 are simply numbers the parameters x2 and y2 must also be specified. In this case rect draws a rectangle form x1,y1 to x2,y2 with the color color. If x1 andy1 are arrays, x2 and y2 should be left blank. In this case rect acts the same way as the plot function with the rect respectively fillrect flag set.

    See also

    plot

    show (Draws a image)

    Parameters

              show ( image, position = {}, size = {}, num = 0, linear = 0, 
                     fitColors = 0, floyd = 0, rescale = 0 )
    
              Types: image                  char[]
                     position               double[]
                     size                   double[]
                     num                    int
                     linear                 int
                     fitColors              int
                     floyd                  int
                     rescale                int
    

    Return

              -1
    

    Description

    The show function is used to display images. num is the number of the plot where the image should be drawn (see plot for detail). If the image constist of n x m pixels, show will place it by default from (0,0) to (n,m) inside the plot. With position and size you may change this behaviour, position sets the lower left edge of the image in plot-coordinates and size the width and height.

    The image argument may be a normal image, containing the indexes of the actual colortable, or a true-color image, contaning RGB data. If image is a normal image, you may use the rescale flag to fit the color indexes of the image to the size of the colortable (e.g. the image contain 8 bit data, but the actual device has only a 6 bit colortable). If image is a true-color image you may use the fitColors flag, to change the colortable of the device for a best match to the image. You also may use the floyd flag to enable Floyd-Steinberg dithering of the image.

    The linear flag is used to tell Xi whether the image should be block resized (fast) or linear interpolated (slow).

    See also

    plot

    startbuffer (Open a command buffer)

    Parameters

              startbuffer ( )
    

    Return

              -1
    

    Description

    The startbuffer function is useful if you want to speed up the communication between Xi and the graphic device. After a call startbuffer all graphic commands are stored in an internal buffer and nothing would be drawn. With the flushbuffer you transmit the entire buffer to the graphic device in one packet. This is a great speedup especially for PVM connections.

    With the endbuffer function the command buffer will be closed and Xi acts in the normal way.

    See also

    flushbuffer, endbuffer

    velocity_field (draws a velocity_field)

    Parameters

              velocity_field ( u, v, x = {-1}, y = {-1}, startX = {-1}, 
                               startY = {-1}, colors = {-1}, nstep = 1, 
                               stepSize = 0.1, headScale = 0.5, noaxis = 0, 
                               curve = 0 )
    
              Types: u                      double[]
                     v                      double[]
                     x                      double[]
                     y                      double[]
                     startX                 double[]
                     startY                 double[]
                     colors                 double[]
                     nstep                  int
                     stepSize               double
                     headScale              double
                     noaxis                 int
                     curve                  int
    

    Return

              -1
    

    Description

    velocity_field plots a velocity field with arrows pointing in the direction of the given velocity field. u and v give the X and Y components of the velocity field. If the parameters x and y are given the should be arrays. The size of y must be equal to the first dimension of u, v and x must be equal to the secound dimension of u, v. startX and startY set the start points and the array color sets the colors of each arrow of each arrow. nsteps changes the number of segments of each arrow and stepSize determine the number of segments. The parameter headScale is the proportional factor between the length of the arrow and sides of the arrow-head. Corresponding to the plot command the flag noaixs suppresses the axis. If the segments of the arrows should be connected with splines the flag curve will do the job for you.

    Example

    >u=cos(dincarr(10,15)/20.);
    >v=transpose(sin(dincarr(15,10)/20.));
    >contour(q,\nlevel=7,\curve);
    

    See also

    velocity_field3d

    window (Opens a window and changes it's properties)

    Parameters

              window ( num = -1, bpp = 1, title = "", size = {600,600}, 
                       position = {0,0}, close = 0, name = "", eps = 0, 
                       ppm = 0, pov = 0, t3d = 0, clearAll = 0, background, 
                       map = 0, shm = 0, pvm = 0, WireFrame = 0, 
                       HiddenLine = 0, ConstShade = 0, java = 0, 
                       javadisplay = "", javapath = "java", javadriver = "$XIPATHENV/java/XiWindow", 
                       javaport = 4000 )
    
              Types: num                    int
                     bpp                    int
                     title                  string
                     size                   int[]
                     position               int[]
                     close                  int
                     name                   string
                     eps                    int
                     ppm                    int
                     pov                    int
                     t3d                    int
                     clearAll               int
                     background             int
                     map                    int
                     shm                    int
                     pvm                    int/string
                     WireFrame              int
                     HiddenLine             int
                     ConstShade             int
                     java                   int/string
                     javadisplay            string
                     javapath               string
                     javadriver             string
                     javaport               int
    

    Return

              -1
    

    Description

    window is the basic function to open a graphic-device. Each graphic-device is represented by a number num (-1 means the actual device). The parameter bpp sets the bits per pixel of the device and can NOT be changed afterwards. If you need more colors you have to create a new device with enough bits per pixel.

    There are several general flag for controling a device. The close flag indicates that the device num should be closed and eventually all output should be written to disk. size simply sets the x and y resolution of the device (not valid for the povray device). Since all devices are vectorbased the size can be changed afterward. The clearAll flag is used to clear a device totally, for the X device it is equivalent to use the ClearAll butten.

    If neither the eps flag nor the ppm flag are set window set the properties of a X-graphic-device or opens a new one. title changes the title of the X-window and position sets the x and y coordinates (on the screen) of the upper left corner of the window. If position is not given the window will be placed anywhere on the screen (depending on the window-manager). With the background flag you enable the background draw of the X device, all drawing commands acts a background and could be map on screen by the map flag. This is useful if you want to create small animations in Xi

    If the eps flag or the ppm flag are set window will be an EPS- respectively PPM-graphic-device. name sets the outputname for both devices. If name is not given a file "xigraph.eps" respectively "xigraph.ppm" will be written. Note that the size of the EPS-graphic-device is measured in units of 1/10 Milimeters. By default the size of an EPS-device is 1200x1200 i.e. 12x12 centimeters.

    The t3d flag indicates that the device shoult accept 3d graphic commands. If you simply set t3d Xi will open a 3d X device, if you use it combined with the eps flag Xi opens a 3d EPS device (the 3d PPM device isn't supported jet). Since the povray device (defined by pov) is a 3d device by itself the t3d isn't necessary. The WireFrame, HiddenLine and ConstShade flags are only useful for the 3d X and 3d EPS device, with these options one define if the 3d data is display as wire frame (fastest), hidden line or constant shading (slowest) model.

    The pvm an shm flags are used to define want type of communication between Xi and the graphic devices should be used. shm define a shared memory communication (very fast, but only supported on some systems jet) and pvm uses PVM communication (you have to install a pvm daemon). With pvm you are able to run Xi and the graphic device on different computers. Last at least there are 5 JAVA-Flags: if java is set, then xi starts the xigraph device as java-standalone-application, javadisplay sets the displaying host, javapath determines the path of the java interpreter (including the name of the interpreter, "java"), javadriver contains the path of the applet, called "XiWindow.class" (including its name without ".class" extension) and javaport is the base port number (important for communication between sockets; the absolute number is calculated by port=javaport+2*num; if a portnumber is destroyed, you have to add 2 to the old javaport parameter).


    xyouts (Draws text at arbitrary places)

    Parameters

              xyouts ( x, y, text, height = 0.05, rotation = 0.0, 
                       align = 0, font = 0 )
    
              Types: x                      double/double[]
                     y                      double/double[]
                     text                   string
                     height                 double
                     rotation               double
                     align                  int
                     font                   int
    

    Return

              -1
    

    Description

    The xyouts function is used to place texts in your plots. With the text argument you define what kind of text should be plotted. Xi uses a text coding similar to TeX only that the '\' is replaced by a '!'. The folling specials are implemented:
             !!,!{,!},!^,!_   to write a single '!','{','}','^' or '_'
             { ... }          to mark a textblock
             !em,!it          to switch to italic font
             !rm              to switch to normal font
             !^               to raise a textblock (index)
    	 !_               to lower a textblock (index)
     
    If x and y are merely numbers the text will be placed at these coordinates. If x and y are array the text will be placed along the defined polygon. With height you change the height of the text. With rotation you set the angle of the text, if no path is given. align defines the alignment of the text. The nummerical value for align is the result of the addition of the following numbers:
             0                center alignment (horizontal and/or vertical)
    	 1                right  alignment (horizontal)
    	 2                left   alignment (horizontal)
    	 4                top    alignment (vertical)
    	 8                bottom alignment (vertical)
    	 16               vertical mirror
    	 32               horizontal mirror
     
    Finally with font you may choose between different vector fonts (Hershey fonts):
             0                complex font (default)
             1                complex small font
             2                simplex font
    	 3                triplex font (nice but slow)
     

    © 1995 by Bodo Junglas, Klaus Spanderen and Fabian Weis
    - Last revised: Wed Jun 19 16:58:32 1996